home *** CD-ROM | disk | FTP | other *** search
/ Info-Mac 3 / Info_Mac_1994-01.iso / Development / General / DebugWindow 1.4 / DebugWindow Docs < prev    next >
Text File  |  1993-09-08  |  6KB  |  165 lines
  1. 
  2.                                                        DebugWindow
  3.  
  4.                                                     by Keith Ledbetter
  5.  
  6.                                      This program may be freely distributed.
  7.  
  8. ••••
  9. Note: DebugWindow requires System 7
  10. ••••
  11.  
  12.  
  13.    DebugWindow is a utility that mimics the Windows 3.x program of the same name.
  14. It allows you to easily print out display strings during the development stages of
  15. your program without any of the headaches normally associated with built-in
  16. "standard I/O" functions.   
  17.  
  18.  
  19.  
  20.  
  21.     DebugWindow's features:
  22.  
  23.  
  24.   •  full "printf()" functionality for C programmers without any added coding on
  25.       your part
  26.  
  27.   •  will remember its location and size on the screen across sessions
  28.  
  29.   •  no more hassles of trying to incorporate Think C's "stdio" window
  30.       in with your pure Toolbox code
  31.  
  32.   •  allows you to save any information that you've printed into its window to a
  33.       TeachText document 
  34.  
  35.   •  callable from either Think C or Hypercard
  36.  
  37.  
  38.  
  39. How does DebugWindow work?
  40. ---------------------------
  41.  
  42.  
  43.   DebugWindow is made up of 2 pieces.   The first is the stand-alone program that sits quietly in the background waiting for an Apple Event to come along for it.   The second piece is either (a) a very small ".lib" file that you include in your Think C (5.x or 6.x)
  44. project or (b) a code resource that you copy into your Hypercard stack with ResEdit.   These pieces contain the "Debug()" function that you call whenever you want to display a string to the DebugWindow.   The "DebugWindow.Lib" file is totally self-contained;  all you need to do to add the functionality to your C program is:
  45.  
  46.     •  Add the "DebugWindow.Lib" file to your Think C project
  47.  
  48.     •  #include "Debug.h" in each of your source files that needs it.
  49.  
  50.     •  if you're not already using one of the ANSI libraries in your
  51.         project, you'll need to add the ANSI-Small library.
  52.  
  53.     •  make sure that the "High Level Events" flag is checked in your
  54.         "Set Project Type / Size" resource.
  55.  
  56.  
  57. or to your Hypercard stack:
  58.  
  59.     •   use ResCopy or ResEdit to copy the code resource "xDebug" into your
  60.          Hypercard stack.
  61.  
  62.  
  63.  
  64. That's it!   Now you can place Debug (or xDebug) statements throughout your C or Hypercard program whenever you feel the need.   For example:
  65.  
  66.  
  67. void MyFunction (short xPos, short yPos)
  68. {
  69.     Debug ( "Doing MyFunction() routine: position is %d,%d\n", xPos, yPos );
  70.     ....    
  71.     if ( yPos < 0 )
  72.         Debug ( "Ack!  Invalid yPos passed by calling function! (%d)\n", yPos );
  73.     .....
  74.     ....
  75. }
  76.  
  77.  
  78. or....
  79.  
  80.  
  81. void GetDataFromHost ()
  82. {
  83.     ....do the DAL stuff....
  84.  
  85.     Debug ( "This data was received from the host:\n" );
  86.     for ( x = 0; x < totalLinesReceived; ++x )
  87.         Debug ( "Host line [%2d]: %-20s %s\n", x, tableName[x], tableVal [x]);
  88.     ....
  89. }
  90.  
  91.  
  92.  
  93. DebugWindow Preferences
  94. ------------------------
  95.  
  96.  
  97.     If the "Automatically add a Carriage Return" box is checked, DebugWindow will
  98. tack a carriage return on the end of any incoming text automatically.   This means
  99. that you don't have to keep remembering to put a "\r" or "\n" on the end of all of
  100. your Debug() strings.
  101.  
  102.  
  103.     If the "Remember Last Position" box is checked, DebugWindow will remember
  104. its window placement and size across executions of the program.
  105.  
  106.  
  107.  
  108. In Conclusion
  109. ------------
  110.  
  111.     If you have any enhancement ideas or questions about DebugWindow (especially if
  112. you find any problems), you can contact me electronically through any of the ID's
  113. listed in the program's "About Box".
  114.  
  115.  
  116. Enjoy!
  117.  
  118.     Keith Ledbetter
  119.       
  120.  
  121.  
  122. Revision History
  123.  
  124.  
  125.   v1.0    • Initial release to a very limited audience.
  126.  
  127.   v1.1    • The "sending program" (that's you) now waits for a reply
  128.                       from DebugWindow; this means that on large streams of
  129.                 Debug() calls, the strings will be immediately displayed
  130.                 in the debug window instead of getting "batched" up.
  131.  
  132.             • DebugWindow will now clear out the display window
  133.                automatically when the buffer is about to fill up.
  134.  
  135.             •    Wrote an XCMD so that Hypercard developers can send
  136.                 messages to DebugWindow.   Simply copy the "xDebug"
  137.                 code resource into your Hypercard stack, and invoke it
  138.                 like this:
  139.  
  140.                                xDebug "This string goes to the DebugWindow" & return
  141.  
  142.   v1.2    •  Internal testing and changes.
  143.  
  144.   v1.3    •  First general public release.
  145.  
  146.   v1.4    •  Added two "tilde lead-in" commands to DebugWindow:
  147.  
  148.                               ~c tells DebugWindow to clear its screen
  149.                         ~t tells DebugWindow to display a timestamp
  150.  
  151.                  These are now implemented in DebugWindow.Lib as 
  152.                  ClearDebugWindow() and DebugTimestamp().  Those of
  153.                  you using Hypercard can simply pass the strings to
  154.                  xDebug as in:   xDebug "~c"
  155.  
  156.             • I've received so many requests for "special" versions of
  157.                DebugWindow.Lib (ie: Pascal, A4, PowerPC, MacApp..) that
  158.                I have decided to include the source code to DebugWindow.Lib
  159.               with this release.   You should find everything you need to know
  160.               in the enclosed Debug.c to implement DebugWindow in whatever
  161.               environment you see fit (you'll need at least some knowledge of
  162.               Apple Events).   Of course, if you have any questions at all, feel
  163.               free to drop me an Email.
  164.  
  165.